Download
FAQ
History
HomeHomeNext API
Search
Feedback
Divider

Creating a Web Service with JAX-RPC

This section shows how to build and deploy a simple Web service called MyHelloService. A later section, Creating Web Service Clients with JAX-RPC, provides examples of JAX-RPC clients that access this service. The source code required by MyHelloService is in <INSTALL>/j2eetutorial14/examples/jaxrpc/helloservice/.

These are the basic steps for creating the service:

  1. Code the the service endpoint interface and implementation class.
  2. Build and generate the files required by the service.
  3. Use deploytool to package the service's files into a WAR file.
  4. Deploy the WAR file.

The sections that follow cover these steps in greater detail. Before proceeding, you should try out the examples in the Getting Started with Web Applications chapter. Make sure that you've followed the instructions in Setting Up To Build and Deploy Tutorial Examples.

Coding the Service Endpoint Interface and Implementation Class

A service endpoint interface declares the methods that a remote client may invoke on the service. In this example, the interface declares a single method named sayHello.

A service endpoint interface must conform to a few rules:

In this example, the service endpoint interface is HelloIF.java:

package helloservice;

import java.rmi.Remote;
import java.rmi.RemoteException;

public interface HelloIF extends Remote {
    public String sayHello(String s) throws RemoteException;
} 

In addition to the interface, you'll need the class that implements the interface. In this example, the implementation class is called HelloImpl:

package helloservice;

public class HelloImpl implements HelloIF {

    public String message ="Hello";

    public String sayHello(String s) {
        return message + s;
    }
} 

Building the Service

To build MyHelloService, in a terminal window go to the <INSTALL>/j2eetutorial14/examples/jaxrpc/helloservice/ directory and type the following:

asant build 

The preceding command executes three asant tasks:

  1. compile-service
  2. generate-wsdl
  3. generate-mapping

compile-service

This asant task compiles HelloIF.java and HelloImpl.java, writing the class files to the build subdirectory.

generate-wsdl

The generate-wsdl task runs the wscompile tool, which creates the MyHelloService.wsdl file in the build directory. The generate-wsdl task runs wscompile as follows:

wscompile -define -d build/server -nd build 
-classpath build config-interface.xml 

The -define flag instructs the tool to read the service endpoint interface and to create a WSDL file. The -d and -nd flags tell the tool to write output to the build subdirectory. The tool reads the following config-interface.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<configuration 
  xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">
  <service 
      name="MyHelloService" 
      targetNamespace="urn:Foo" 
      typeNamespace="urn:Foo" 
      packageName="helloservice">
      <interface name="helloservice.HelloIF"/>
  </service>
</configuration> 

The config.xml-interface file tells wscompile to create a WSDL file with the following information:

generate-mapping

This asant task also runs wscompile, this time to create a mapping.xml file and a set of runtime classes. The mapping.xml file maps the package names of the service classes to a namespace URI of the WSDL file. The set of runtime classes is made up of serializers, deserializers, and ties. The generate-maping task runs wscompile as follows:

wscompile -gen -d build -nd build -mapping build/mapping.xml 
-classpath build config-wsdl.xml 

The -gen flag instructs the tool to read the WSDL file and to create the runtime classes. The -d and -nd flags tell the tool to write output to the build subdirectory, and the -mapping flag specifies the mapping file. The tool reads the following config-wsdl.xml file:

<?xml version="1.0" encoding="UTF-8"?>
  <configuration
     xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">
     <wsdl location="build/MyHelloService.wsdl"
     packageName="helloservice"/>
  </configuration> 

Packaging the Service

Behind the scenes, a JAX-RPC Web service is actually a servlet. Because a servlet is a Web component, to package the service you run the New Web Component wizard of the deploytool utility. During this process the wizard performs the following tasks.

To start the New Web Component wizard, select FileRight ArrowNewRight ArrowWeb Application WAR. The wizard displays the following dialog boxes.

  1. Introduction dialog box
    1. Read the explanatory text for an overview of the wizard's features.
    2. Click Next.
  2. WAR File dialog box
    1. Select the button labelled Create New Stand-Alone WAR Module.
    2. In the WAR Location field, enter <INSTALL>/j2eetutorial14/examples/jaxrpc/helloservice/MyHelloService.war.
    3. In the WAR Display Field, enter MyHelloService.
    4. Click Edit.
    5. In the tree under Available Files, locate the <INSTALL>/j2eetutorial14/examples/jaxrpc/helloservice/ directory.
    6. Select the build subdirectory.
    7. Click Add.
    8. Click OK.
    9. Click Next.
  3. Choose Component Type dialog box
    1. Select the Web Services Endpoint button.
    2. Click Next.
  4. Choose Service dialog box
    1. In the WSDL File combo box, select MyHelloService.wsdl.
    2. In the Mapping File combo box, select mapping.xml.
    3. Click Next.
  5. Web Service Endpoint dialog box
    1. In the Service Endpoint Interface combo box, select helloservice.HelloIF.
    2. In the Namespace field, enter urn:Foo.
    3. In the Local Part field, enter HelloIFPort.
    4. Bug 4866894: Do not enter the Endpoint Address URI in this dialog.
    5. Click Next.
  6. Component General Properties dialog box
    1. In the Service Endpoint Implementation combo box, select helloservice.HelloImpl.
    2. Click Finish.

Specifying the Endpoint Address

To access MyHelloService, the tutorial clients will specify this service endpoint address URI:

http://localhost:1024/hello-jaxrpc/hello 

The /hello-jaxrpc string is the context root of the servlet that implements MyHelloService. The /hello string is the servlet alias. To specify the endpoint address, you set the context root and alias as follows:

  1. In deploytool, select MyHelloService in the tree.
  2. Select the General tab.
  3. In the Context Root field, enter hello-jaxrpc.
  4. In the tree, select HelloImpl.
  5. Select the Aliases tab.
  6. In the Component Aliases table, add /hello. (Don't forget the forward slash.)
  7. Select FileRight ArrowSave.

Bug 4866894: Do not enter the Service Endpoint Address URI in the Endpoint tab of HelloImpl.

Deploying the Service

In deploytool, perform these steps:

  1. In the tree, select MyHelloService.
  2. Select ToolsRight ArrowDeploy.

Now you are ready to create a client that accesses this service.

Divider
Download
FAQ
History
HomeHomeNext API
Search
Feedback
Divider

All of the material in The J2EE 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.